<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>ECF Shared Object Factory</title>
<style type="text/css">@import url("../../../../org.eclipse.platform.doc.isv/book.css");</style>
<style type="text/css">@import url("../../../../org.eclipse.platform.doc.isv/schema.css");</style>
</HEAD>
<BODY>
<H1 style="text-align:center">ECF Shared Object Factory</H1>
<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Identifier: </h6>org.eclipse.ecf.sharedObjectFactory<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Since: </h6>0.6.0
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">Description: </h6>ECF Shared Object Factory extension point (<b>org.eclipse.ecf.sharedObjectFactory</b>.  This extension point allows implmenters to define an <b>org.eclipse.ecf.core.sharedobject.provider.ISharedObjectInstantiator</b> that will be responsible for creating
<b>org.eclipse.ecf.core.sharedobject.ISharedObject</b> instances when requested by clients.  Here is the <b>ISharedObjectInstantiator</b> that
extensions must implement:

<pre class="Example"><span class="code SchemaTag">
public interface ISharedObjectInstantiator {
 /**
  * Create instance of ISharedObject. This is the interface that plugin
  * implementations must implement for the sharedObjectFactory extension
  * point. The caller may optionally specify both argument types and
  * arguments that will be passed into this method (and therefore to the
  * provider implementation implementing this method). For example:
  * &lt;p&gt;
  * &lt;/p&gt;
  * &lt;p&gt;
  * &lt;b&gt;
  * SharedObjectFactory.getDefault().createSharedObject("foosharedobject",new
  * String [] { java.lang.String }, new Object { "hello" });&lt;/b&gt;
  * &lt;/p&gt;
  * &lt;p&gt;
  * &lt;/p&gt;
  * 
  * @param typeDescription
  *            the SharedObjectTypeDescription associated with the registered
  *            shared object provider implementation plugin
  * @param args
  *            arguments specified by the caller. May be null if no arguments
  *            are passed in by caller to
  *            SharedObjectFactory.getDefault().createSharedObject(...)
  * @return ISharedObject instance. The provider implementation must return a
  *         valid object implementing ISharedObject OR throw a
  *         SharedObjectCreateException
  * @throws SharedObjectCreateException
  *             if shared object instance cannot be created
  */
 public ISharedObject createInstance(
   SharedObjectTypeDescription typeDescription, Object[] args)
   throws SharedObjectCreateException;
}
</span></pre><p></p>
<h6 class="CaptionFigColumn SchemaHeader">Configuration Markup:</h6>
<p></p>
<p class="code SchemaDtd">&lt;!ELEMENT <a name="e.extension">extension</a> (<a href="#e.sharedObjectFactory">sharedObjectFactory</a>+)&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST extension</p>
<p class="code SchemaDtdAttlist">point&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">id&nbsp;&nbsp;&nbsp;&nbsp;CDATA #IMPLIED</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;CDATA #IMPLIED&gt;</p>
<p></p>
<ul class="ConfigMarkupAttlistDesc">
</ul>
<br><p class="code SchemaDtd">&lt;!ELEMENT <a name="e.sharedObjectFactory">sharedObjectFactory</a> (<a href="#e.property">property</a>*)&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST sharedObjectFactory</p>
<p class="code SchemaDtdAttlist">class&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDATA #IMPLIED</p>
<p class="code SchemaDtdAttlist">description&nbsp;CDATA #IMPLIED&gt;</p>
<p></p>
<ul class="ConfigMarkupAttlistDesc">
<li><b>class</b> - The fully qualified name of the class that implements the <b>org.eclipse.ecf.core.provider.ISharedObjectInstantiator</b> interface.</li>
<li><b>name</b> - An optional name for the extension.  If no name is explicitly provided by the extension, the sharedObjectFactory class name is used as the name.  Note that this name must <b>not</b> conflict with any other name in the ECF SharedObjectFactory in order to be successfully registered.  Care should therefore be taken in selection of a name such that it does not conflict with other pre-existing names for this factory implementations</li>
<li><b>description</b> - </li>
</ul>
<br><p class="code SchemaDtd">&lt;!ELEMENT <a name="e.property">property</a> EMPTY&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST property</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">value&nbsp;CDATA #REQUIRED&gt;</p>
<p></p>
<p class="ConfigMarkupElementDesc">
Property (name,value) associated with SharedObjectTypeDescription</p>
<br>
<ul class="ConfigMarkupAttlistDesc">
<li><b>name</b> - The name of the property</li>
<li><b>value</b> - The value of the property</li>
</ul>
<br><h6 class="CaptionFigColumn SchemaHeader">Examples: </h6>Here's an example of an extension point declaration:

<pre class="Example"><span class="code SchemaTag">
   &lt;extension
         point=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.sharedobject.sharedObjectFactory&quot;</span><span class="code SchemaTag">&gt;
      &lt;sharedObjectFactory
            class=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.tests.provider.TestSharedObjectInstantiator&quot;</span><span class="code SchemaTag">
            name=</span><span class="code SchemaCstring">&quot;ecf.test.sharedobjectfactory&quot;</span><span class="code SchemaTag">/&gt;
   &lt;/extension&gt;
</span></pre>

and the TestSharedObjectInstantiator is defined:

<pre class="Example"><span class="code SchemaTag">
public class TestSharedObjectInstantiator implements ISharedObjectInstantiator {

 public ISharedObject createInstance(SharedObjectTypeDescription description, Object[] args) throws SharedObjectCreateException {
  System.out.println("createInstance("+description+","+((args==null)?"null":Arrays.asList(args).toString()));
  return new TestSharedObject();
 }
}
</span></pre>

<h3>Example Usage of Container by Clients</h3>

Clients may use the extension via calls such as:

<pre class="Example"><span class="code SchemaTag">
ISharedObject obj = SharedObjectFactory.getDefault().createSharedObject("ecf.test.sharedobjectfactory");
</span></pre>
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">API Information: </h6>The API for accessing the functionality provided via extensions is via <b>org.eclipse.ecf.core.sharedobject.SharedObjectFactory.getDefault()</b> methods.  Specifically, the <b>org.eclipse.ecf.core.sharedobject.ISharedObjectFactory.createSharedObject()</b> methods are to be used to create shared
object instances, where extensions implement the actual shared object creation  

Here is the <b>org.eclipse.ecf.core.sharedobject.ISharedObjectFactory</b> contract implemented by the <b>org.eclipse.ecf.core.sharedobject.SharedObjectFactory</b>:

<pre class="Example"><span class="code SchemaTag">
public interface ISharedObjectFactory {
 /*
  * Add a SharedObjectTypeDescription to the set of known
  * SharedObjectTypeDescriptions.
  * 
  * @param scd the SharedObjectTypeDescription to add to this factory @return
  * SharedObjectTypeDescription the old description of the same name, null if
  * none found
  */
 public SharedObjectTypeDescription addDescription(
   SharedObjectTypeDescription description);

 /**
  * Get a collection of the SharedObjectTypeDescriptions currently known to
  * this factory. This allows clients to query the factory to determine what
  * if any other SharedObjectTypeDescriptions are currently registered with
  * the factory, and if so, what they are.
  * 
  * @return List of SharedObjectTypeDescription instances. Will not be null.
  */
 public List getDescriptions();

 /**
  * Check to see if a given named description is already contained by this
  * factory
  * 
  * @param description
  *            the SharedObjectTypeDescription to look for
  * @return true if description is already known to factory, false otherwise
  */
 public boolean containsDescription(SharedObjectTypeDescription description);

 /**
  * Get the known SharedObjectTypeDescription given it&apos;s name.
  * 
  * @param name
  * @return SharedObjectTypeDescription found. Null if description not found.
  * @throws SharedObjectCreateException
  */
 public SharedObjectTypeDescription getDescriptionByName(String name)
   throws SharedObjectCreateException;

 /**
  * Create ISharedObject instance. Given a SharedObjectTypeDescription
  * object, a String [] of argument types, and an Object [] of parameters,
  * this method will
  * &lt;p&gt;
  * &lt;ul&gt;
  * &lt;li&gt;lookup the known SharedObjectTypeDescriptions to find one of
  * matching name&lt;/li&gt;
  * &lt;li&gt;if found, will retrieve or create an ISharedObjectInstantiator for
  * that description&lt;/li&gt;
  * &lt;li&gt;Call the ISharedObjectInstantiator.createInstance method to return
  * an instance of ISharedObject&lt;/li&gt;
  * &lt;/ul&gt;
  * 
  * @param typeDescription
  *            the SharedObjectTypeDescription to use to create the instance
  * @param args
  *            an Object [] of arguments passed to the createInstance method
  *            of the ISharedObjectInstantiator
  * @return a valid instance of ISharedObject. Will not be null.
  * @throws SharedObjectCreateException
  *             if shared object cannot be created
  */
 public ISharedObject createSharedObject(
   SharedObjectTypeDescription typeDescription, Object[] args)
   throws SharedObjectCreateException;

 /**
  * Create ISharedObject instance. Given a SharedObjectTypeDescription name,
  * this method will
  * &lt;p&gt;
  * &lt;ul&gt;
  * &lt;li&gt;lookup the known SharedObjectTypeDescriptions to find one of
  * matching name&lt;/li&gt;
  * &lt;li&gt;if found, will retrieve or create an ISharedObjectInstantiator for
  * that description&lt;/li&gt;
  * &lt;li&gt;Call the ISharedObjectInstantiator.createInstance method to return
  * an instance of ISharedObject&lt;/li&gt;
  * &lt;/ul&gt;
  * 
  * @param descriptionName
  *            the SharedObjectTypeDescription name to lookup
  * @return a valid instance of ISharedObject. Will not be null.
  * @throws SharedObjectCreateException
  */
 public ISharedObject createSharedObject(String descriptionName)
   throws SharedObjectCreateException;

 /**
  * Create ISharedObject instance. Given a SharedObjectTypeDescription name,
  * this method will
  * &lt;p&gt;
  * &lt;ul&gt;
  * &lt;li&gt;lookup the known SharedObjectTypeDescriptions to find one of
  * matching name&lt;/li&gt;
  * &lt;li&gt;if found, will retrieve or create an ISharedObjectInstantiator for
  * that description&lt;/li&gt;
  * &lt;li&gt;Call the ISharedObjectInstantiator.createInstance method to return
  * an instance of ISharedObject&lt;/li&gt;
  * &lt;/ul&gt;
  * 
  * @param descriptionName
  *            the SharedObjectTypeDescription name to lookup
  * @param args
  *            the Object [] of arguments passed to the
  *            ISharedObjectInstantiator.createInstance method
  * @return a valid instance of IContainer. Will not be null.
  * @throws SharedObjectCreateException
  */
 public ISharedObject createSharedObject(String descriptionName,
   Object[] args) throws SharedObjectCreateException;

 /**
  * Remove given description from set known to this factory.
  * 
  * @param scd
  *            the SharedObjectTypeDescription to remove
  * @return the removed SharedObjectTypeDescription, null if nothing removed
  */
 public SharedObjectTypeDescription removeDescription(
   SharedObjectTypeDescription scd);
}
</span></pre>

See the "Examples" page for an example usage of the extension point.
<p></p>

<br>
<p class="note SchemaCopyright">
Copyright (c) 2004 Composent, Inc. and others.

This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at https://www.eclipse.org/legal/epl-2.0/

SPDX-License-Identifier: EPL-2.0

</p>
</BODY>
</HTML>
